Summary

Two related refactors that make editor-wide behaviors (syntax highlighting, source-with-preview) into single user- or default-provided extensions instead of configuration wired into each block, and — on the back of the highlighting change — extend syntax highlighting to inline content (e.g. inline math).

1. Syntax highlighting is a standalone extension

Syntax highlighting is now a standalone extension the user provides to the editor, rather than configuration wired into each block.

Previously the highlighter (createHighlighter) lived on the code block's options (and the math block's), and each block self-registered a shared SyntaxHighlightingExtension singleton. That meant the highlighter config was duplicated onto every block that wanted it, and — relying on silent de-dup-by-key — whichever block registered first silently won the config while the other was dropped.

Now:

• Syntax highlighting is opt-in via the editor's extensions option. The block schema is unchanged — code and math blocks keep declaring how to highlight their contents via meta.highlight ((block) => block.props.language for code, () => "latex" for math). When the extension is present, it highlights whichever blocks declare a language; when it's absent, they render as editable plain text.
• @blocknote/code-block exports a ready-to-use syntaxHighlighter extension, pre-configured with its bundled Shiki highlighter (github themes). For a custom highlighter, build one with the SyntaxHighlightingExtension factory from @blocknote/core.

import { codeBlockOptions, syntaxHighlighter } from "@blocknote/code-block";

useCreateBlockNote({
  extensions: [syntaxHighlighter],
  schema: BlockNoteSchema.create().extend({
    blockSpecs: { codeBlock: createCodeBlockSpec(codeBlockOptions) },
  }),
});

Rationale

The earlier approach depended on the ExtensionManager silently de-duplicating extensions by key ("first registration wins"). That resolves the "code block and math block both configure a highlighter" conflict, but does so by silently discarding one configuration — a subtle bug waiting to happen, and it leaves it ambiguous which instance's config is actually used.

Making syntax highlighting a single user-provided extension removes the conflict at its source: there's exactly one highlighter, registered once, and it highlights every block that declares a language. Config is no longer duplicated across blocks.

On the back of that, this PR also replaces silent de-duplication with a hard error: registering two extensions with the same key now throws, from any source (direct registration or a blockNoteExtensions dependency). Extension keys must be unique; a shared extension must be registered once rather than by each consumer. This is safe because the only real duplicate-key case in the codebase was the code + math highlighter, which this refactor removes — and the sole blockNoteExtensions user (CollaborationExtension) has unique sub-extension keys, verified at runtime.

2. Inline content syntax highlighting

Syntax highlighting now also works for inline content (e.g. inline math), not just blocks.

• SyntaxHighlightingExtension discovers highlightable nodes by scanning both blockSpecs and inlineContentSpecs for a meta.highlight callback (blocks with content: "inline", inline content with content: "styled"). Inline math declares highlight: () => "latex", so its LaTeX source is highlighted in the editable popup like the block version.
• This required an upstream fix in prosemirror-highlight: it previously collected only text-block nodes, so inline nodes were never highlighted. Since v0.15.3 it collects nodes by node.inlineContent (ocavue/prosemirror-highlight#137), so inline nodes that hold inline content are visited alongside text blocks. This PR bumps prosemirror-highlight to ^0.15.3; no local patch is needed.

3. SourceBlockWithPreview is a single default extension

SourceBlockWithPreviewExtension (and its inline sibling SourceInlineContentWithPreviewExtension) are now single editor-wide extensions registered once by default, mirroring the syntax-highlighting pattern — instead of being instantiated per block/inline-content spec.

Previously each preview block constructed the extension itself, passing a bespoke key, a blockType/inlineContentType, an always-() => true hasPreview callback, an enterBehaviour string, and runsBefore.

Now:

• Both preview extensions are included in getDefaultExtensions and registered once. Blocks/inline content opt in by declaring meta.hasPreview: true in their spec (self-discovered from the schema, the same way meta.highlight is), instead of the extension being told a block/inline type.
• The always-true hasPreview callback, key, and runsBefore options are gone.
• The bespoke enterBehaviour: "close" | "newline" option is replaced by the existing, schema-driven meta.hardBreakShortcut: single-line sources (math) leave it default; multi-line sources (diagram) set hardBreakShortcut: "enter", which the preview extension reads from the spec to decide whether Enter inserts a line break or commits/closes the popup.

Changes

• @blocknote/core
  • Syntax highlighting: remove createHighlighter from CodeBlockOptions; remove the code block's self-registration of the highlighting extension (keeps meta.highlight). Remove the dead editor-level syntaxHighlighting option from BlockNoteEditorOptions. ExtensionManager now throws on any duplicate extension key instead of silently de-duplicating; the blockNoteExtensions ordering edge is retained. Fix stale doc comments to describe the real meta.highlight mechanism.
  • Inline highlighting: collectHighlightNodeTypes also collects inline-content specs with a meta.highlight; add highlight/hasPreview to the inline meta types. Bump prosemirror-highlight to ^0.15.3.
  • SourceBlockWithPreview: turn SourceBlockWithPreviewExtension and SourceInlineContentWithPreviewExtension into editor-wide singletons registered in getDefaultExtensions; drop the key/blockType/inlineContentType/hasPreview-callback/enterBehaviour/runsBefore options in favor of meta.hasPreview + meta.hardBreakShortcut. Add hasPreview to BlockConfigMeta and the inline meta types. Note that KeyboardShortcutsExtension reads hardBreakShortcut off the block config (which carries no meta) — flagged with a comment for a follow-up; the preview extension reads it from the spec implementation instead.
• @blocknote/code-block: drop createHighlighter from codeBlockOptions; export a pre-configured syntaxHighlighter extension.
• @blocknote/math-block: remove the highlighter option and self-registration; keep highlight: () => "latex" (block and inline); declare meta.hasPreview instead of constructing the preview extension.
• @blocknote/diagram-block: declare meta.hasPreview + meta.hardBreakShortcut: "enter" + highlight: () => "mermaid" instead of constructing the preview extension with enterBehaviour: "newline".
• Examples & docs: theming/code-block, theming/custom-code-block (bring-your-own bundle), custom-schema/math-block, and custom-schema/diagram-block now pass the extension via extensions: [...]; code-blocks docs updated to the new API.

Impact

Breaking changes to the in-progress branch API:

• createHighlighter is no longer accepted on createCodeBlockSpec / createMathBlockSpec options, and the editor-level syntaxHighlighting option is removed. To enable highlighting, add syntaxHighlighter (or your own SyntaxHighlightingExtension) to extensions.
• Registering two extensions with the same key now throws instead of silently keeping the first.
• SourceBlockWithPreviewExtension / SourceInlineContentWithPreviewExtension no longer take options (key, blockType/inlineContentType, hasPreview, enterBehaviour, runsBefore). Preview blocks opt in via meta.hasPreview (and meta.hardBreakShortcut for multi-line source behavior) rather than constructing the extension.

Testing

• Unit tests: ExtensionManager (unique-key throws for direct dupes, blockNoteExtensions dupes, and shared-sub dupes; single dependencies still register), code-block, SyntaxHighlighting (including collectHighlightNodeTypes block/inline collection), a new inlineHighlight suite (inline nodes are highlighted, non-matching and atom inline nodes are not), and math-block / diagram-block popup keyboard handling (incl. math single-line commit vs diagram multi-line newline). Full @blocknote/core suite passes.
• Typecheck (tsgo) clean across core, code-block, math-block, diagram-block, react, and the modified examples. Lint clean.
• Runtime: verified in the browser that theming/code-block, theming/custom-code-block, custom-schema/math-block, and custom-schema/diagram-block all produce Shiki-highlighted token spans — including inline math, whose LaTeX source now shows highlighted tokens (e.g. \pi colored) where it previously did not. Verified the collaboration examples and the full default-block schema mount with no duplicate-key errors.

Checklist

• Code follows the project's coding standards.
• Unit tests covering the new feature have been added.
• All existing tests pass.
• The documentation has been updated to reflect the new feature